Skip to main content

​
Installation

This guide walks you through installing BindAI and preparing your development environment.

​
Requirements

Before installing BindAI, make sure you have:
  • Python 3.11 or newer
  • pip
  • Git (recommended for source development)
  • uv for source development
Verify your Python version:
BindAI currently supports Python 3.11 and newer.

​
Install BindAI from PyPI

The easiest way to install the published BindAI package is from PyPI:
You can also use:
After installation, verify the BindAI CLI:
The current CLI version is:
Note: bindai --version is not currently supported. Use bindai version.

​
Verify the Python Package

Verify that the BindAI Python package is available:
Expected output:

​
Create Your First Project

Generate a new BindAI project:
Move into the generated project:
The generated project provides the structure needed to build a BindAI application.

​
Configure Environment Variables

AI providers generally require credentials. Configure the required credentials in your environment or project .env file. For example:
Depending on the provider you use, other environment variables may be required. Common provider credentials include:
Local providers such as Ollama may not require an API key. Keep API keys and other credentials out of source control.

​
Verify Your Environment

Run the built-in diagnostics:
The doctor command checks the BindAI environment and reports detected configuration or installation issues.

​
Run Your Project

Start the generated application:
If the required configuration is available, the generated project can start its BindAI application environment.

​
Install BindAI from GitHub for Development

If you want to contribute to BindAI or work with the latest source code, clone the repository:
BindAI is organized as a multi-package uv workspace. The repository contains multiple BindAI packages under:
The workspace includes separate packages for areas such as:
  • Core functionality
  • Agents
  • Tools
  • Providers
  • Memory
  • Embeddings
  • Retrieval
  • Knowledge
  • Workflows
  • Projects
  • Connections
  • MCP
  • CLI

​
Install uv

If uv is not already installed, install it with:
Verify the installation:

​
Synchronize the Development Workspace

From the repository root, run:
This synchronizes the workspace dependencies and creates or updates the development virtual environment.

​
Activate the Development Environment

​
Windows PowerShell

​
macOS / Linux

After activation, your terminal should display the active environment.

​
Verify the Source Installation

Verify that Python is using the workspace environment:
Then verify the BindAI package:
Expected output:
Finally, verify the CLI:
The current CLI version should be:

​
Important: Do Not Use Root-Level Editable Installation

Because the BindAI repository is a multi-package uv workspace, do not run:
from the repository root. Use:
instead. Individual BindAI packages are located under:
and are managed together through the workspace configuration. This keeps workspace dependencies consistent across the repository.

​
Development Workflow

When working on BindAI from source, a typical workflow is:
Activate the environment if necessary:

​
Windows PowerShell

Then run the test suite or work on the relevant package. BindAI uses a modular package structure, so changes to one package can be developed and tested independently while still being synchronized through the workspace.

​
Updating BindAI

To upgrade the published PyPI package:
Then verify the installed version:
If you are developing from the source repository, update the repository and synchronize the workspace:

​
Common Issues

​
ModuleNotFoundError

Make sure the correct environment is activated. For source development, activate the workspace environment.

​
Windows PowerShell

​
macOS / Linux

Then verify:

​
CLI Not Found

If the bindai command is unavailable after installation, make sure the environment containing BindAI is activated. For source development, activate the .venv created by uv sync. You can also verify which Python executable is being used:
Then verify:

​
Missing API Key

If a provider reports an authentication error, verify that the required environment variable is configured. For example:
Make sure the variable is available to the environment in which BindAI is running. If you use a .env file, ensure it is located where your application expects it and that your application loads environment variables appropriately.

​
Unsupported Python Version

Check your Python version:
BindAI requires Python 3.11 or newer.

​
Provider Configuration Issues

If your application cannot connect to a language model:
  1. Verify that the required API key or local provider configuration is available.
  2. Confirm the selected provider.
  3. Confirm that the selected model is supported by that provider.
  4. Run:
  1. Check the provider-specific documentation for additional configuration requirements.
Current provider integrations include:
  • OpenAI
  • Anthropic
  • Google Gemini
  • Groq
  • Ollama
  • OpenRouter

​
Workspace Installation Issues

If source dependencies appear to be missing or inconsistent, run:
Make sure the command is executed from the BindAI repository root. Avoid installing the entire repository with:
The repository is managed as a multi-package workspace.

​
Next Steps

After installing BindAI, continue with: These guides introduce the core BindAI development workflow. As you become familiar with the framework, explore:
  • Tools
  • Memory
  • Knowledge and RAG
  • Workflows
  • Projects
  • Connections
  • MCP
  • Multi-Agent Systems